feat(desiderata): books the library is looking for, and donations from readers - #432

…ake the plugin activatable

The desiderata feature shipped with a manifest requiring a core version that
does not exist yet, so the plugin could not be activated at all — and the
suites that would have caught it exited 0 after printing SKIP, because the
condition they skip on is exactly what the defect causes. Lower requires_app
to the version that actually ships the hooks it needs, build the schema in the
visibility suite instead of skipping, exit non-zero under CI_STRICT_TESTS, and
add a static guard so the next manifest pinned to an unreleased core fails in
one second instead of after a browser run.

The visibility filter reached the catalogue but stopped short of several
surfaces a visitor or a member can still open. Because the book page now 404s
for a request, every listing left unfiltered emits a guaranteed-broken link —
worse than before the feature existed. Filter the remaining public reads: the
search and genre APIs, the calendar feeds, the opera page, the book-club panels,
and the wishlist on both web and mobile. Where a method serves an operator and
a visitor from the same code, the parameter defaults to permissive and only the
public entry point asks for the filter, so admin views keep seeing what the
library is looking for.

Two lists shared one page cursor, so paging the requested books walked the
donation proposals past unread offers and told the librarian none had arrived.
Give each list its own parameter, carry both through every redirect, and say
"nothing more on this page" instead of "nobody has written".

Sixty-six of the plugin's seventy-seven interface strings existed in no locale
file at all, including the whole public donation page, so a non-Italian library
served raw Italian to its visitors. The parity gate could not see it: it
compares the five files against each other, and a string missing from all five
produces no asymmetry. Register them, translate them, and teach the gate to
read the source instead of only its own output.

Wishlist entries are hidden, never deleted: receiving a donation clears the
flag, and the favourite has to come back — with its availability notice — for
the reader who asked for the book in the first place.

The maintenance sweeps that clear the flag deliberately reach soft-deleted rows
and now say so in the statement itself. A restored book that owns copies must
not come back marked as still wanted, which is what scoping them to live rows
would have caused.

…d it

The first round made `is_desiderata` invisible in the catalogue. This round
closes the places that still answered truthfully about a book the catalogue
denies exists, and the places where the check that was supposed to notice
could not have noticed.

OAI-PMH is the one with a standard to answer to. The repository advertises
`deletedRecord="no"` in Identify, and §2.5.1 of the protocol says a repository
that makes that claim must not reveal a deleted status anywhere — so the
de-listing arm of ListRecords, the `book_delisted` marker in the resumption
token's harvest composition, and the de-listing lookup in GetRecord are now all
gated on `hasActiveTriggers()`, which is the same condition Identify already
uses to decide what it advertises. Without the triggers the plugin cannot
record a de-listing, so answering as if it could was both a conformance
violation and a lie about the data.

ResourceSync and the search controller had the mirror-image problem: they
listed or counted wanted titles as if they were holdings. `BookVisibility`
grows `delisted()` next to `catalogue()` so the predicate has one home and
both spellings stay string constants.

The dashboard counter stays deliberately unfiltered, and now says so. It is an
admin counter, and /admin/books, the DataTables total and the export all list
requests — filtering the card alone made it disagree with the list the operator
reaches by clicking it, by exactly the number of wanted titles, with nothing in
the UI explaining the gap. The `/api/autori` count keeps the same reasoning,
with the caveat recorded rather than assumed away: that route chains no
AdminAuthMiddleware while its bulk siblings do, so "operator surface" describes
the intended audience there, not an enforced one. Pre-existing, unchanged by
this work, and the fix is gating the route rather than filtering a count.

The visibility suite was exiting 0 on SKIP, so it could report success without
having run: it now fails loudly under CI_STRICT_TESTS when the trigger it needs
is absent, and covers the three newly gated OAI paths plus the ResourceSync and
search surfaces.

…age beside it

The first three commits gave the feature a public page, an admin page and a
watertight visibility rule. What they did not give it was a place in the
application: the homepage section hung off the end of the render loop outside
the operator's control, a wanted title was unreachable even for someone who
searched for it by name, nothing appeared on the dashboard, and the only way to
record an arrival was through a donor proposal that may never have existed.

This commit closes that distance, and it needed four small, generic extension
points in core rather than one desiderata-shaped hole.

`frontend.home.section` fires inside the ordered loop, in the branch where a
`home_content` row has no core template file. That branch could not fire before,
because every row had one — so the hook is inert until a plugin claims a key. The
plugin now owns a real `home_content` row, which means the existing sortable list
and the visibility toggle govern it like any other section, for free. Its texts
are edited from /admin/cms/home through `cms.home.section.fields` and persisted
through the `cms.home.save` filter, and `cms.home.section_name` gives the row a
proper label instead of a raw key.

The texts are per locale, which `home_content` cannot express — it has one row
per `section_key` and no `locale` column, unlike `cms_pages` and
`email_templates`. Rather than migrate a core table for one plugin's benefit,
the overrides live in `plugin_settings` as JSON keyed by locale, and an empty
field falls back to the shipped `__()` default evaluated in that same locale.
That is the pattern `home-sections/hero.php` already uses, one level deeper.

`admin.dashboard.sections` is the dashboard's first extension point. It is gated
on `$isAdminOrStaff` because `/admin/dashboard` is also served to standard and
premium patrons, so firing it unguarded would run plugin callbacks and put
administrative markup in a reader's page.

Findability needed a predicate of its own. `BookVisibility::discoverable()` is
`catalogue()` unless a plugin widens it, and it accepts exactly the string
`'1=1'` and nothing else — the return value is concatenated into WHERE clauses,
so a filter that could return arbitrary SQL would be an injection point wearing a
hook's clothes. It is used only where a visitor asks for a title by name:
catalogue search with a term, the search preview, and the book's own page.
Browse, feeds, the sitemap, the mobile API and every interop protocol keep
`catalogue()`, so the 33-check visibility suite still holds. A wanted title is
therefore reachable by asking and by link, and never by browsing — an asymmetry,
but the deliberate one: the moment somebody searches for a book we do not own is
exactly the moment a donation gets decided.

The detail page reads `is_desiderata` live rather than from the cached DTO.
`availabilityChanged()` does not bump `book_detail_`, and `DataIntegrity` clears
the flag by itself the moment a copy appears, so a book received through copy
management would have kept showing the badge and the donation form until the
cache expired.

Receiving a book no longer requires a proposal to have existed. The new direct
receipt is transactional with `FOR UPDATE` and `is_desiderata = 1` as its
idempotency key, refuses a book that has open proposals so the donor-tracked
flow stays authoritative, and writes the same `received` audit row as the
proposal path — otherwise the record of how a wanted book entered the catalogue
would depend on which button the operator happened to press.

Unticking the desiderata box on an existing book is that same act. The edit
form's copy field is read-only by core design and the submitted value is
discarded and re-derived from the `copie` table, so unlocking it would have
produced a control that accepts a number, saves, and changes nothing. Instead
the plugin surfaces its own field through `book.save.after`, which fires outside
the core transaction, and the copies it names are really created, inventoried
and audited. Ticking the box back zeroes the count on both the create and the
update path, so a number typed and then reconsidered is never recorded.

An offer that carries an ISBN now proposes its match instead of asking the
operator to search for what the donor already told us. The lookup crosses
ISBN-10 and ISBN-13 through `IsbnFormatter::getAllVariants()`, runs once for the
whole page rather than once per offer, and only ever pre-selects: the operator
confirms, and can always override.

The public search matches the publisher as well as the title, author and ISBN,
and every row carries its cover resolved server-side so the JS-rendered rows and
the server-rendered ones cannot drift apart. The donation form is now a shared
partial, so the homepage, the standalone page and the book page render the same
markup from one file, with the assets printed once per request — a file-level
`static` does not survive a second `require`, because it binds to the including
function rather than to the file.

All of it disappears with the plugin. Deactivation removes the hook rows, so the
predicate narrows back to `catalogue()` by itself; it removes the home row after
snapshotting the operator's position and visibility, so re-activation restores
what they chose rather than resetting it. The version bump to 1.1.0 is what makes
an already-active installation pick any of this up: PluginManager only re-runs
onActivate() when plugin.json is newer, so without it the new hooks would never
register and the feature would be dead code on every existing install.

…it arrives

A proposal that nobody is told about is a proposal that sits. Both events now
reach the people who can act on them: a reader offering a book, and a book
actually entering the catalogue — from a donor proposal, from the direct receipt
button, or from unticking the desiderata box on the book form.

Each event writes one admin_notifications row for the bell, rendered in the
installation locale because it is a single shared row, and then emails every
active admin and staff member separately, each rendered in that recipient's own
locale. NotificationService::notifyAdmins() would have been fewer lines but it
composes the subject and body once, in the acting request's locale, and sends
that same text to everybody — which breaks the house rule that an email renders
in the recipient's language. The duplicated recipient selection is the price of
that rule, and the comment on notifyOperators() says so, so it does not get
"simplified" back later.

The strings are passed as callables rather than as composed text, because
__($variable) is invisible to the locale parity gate: the literals have to stay
at the call site while the locale switch lives in the helper.

Titles are ellipsised past 120 characters. admin_notifications.title and
desiderata_offers.title are both VARCHAR(255), so a long book title prefixed
with "Nuova proposta di donazione: " overflows the INSERT under strict mode and
the notification disappears leaving only a log line.

The whole path is best-effort: the offer row is already committed by the time it
runs, so a mail failure must never turn a donation somebody just typed into a
500 that discards it.

One test change came with this, and it is not cosmetic. Writing the notification
on the request's own connection moves mysqli::$insert_id, and the integration
suite was reading that side channel in three places to learn the id of the offer
it had just created. It now reads the id back from the table, scoped to the
run's unique prefix. The failing assertion was the visible half; the dangerous
half was that the same value feeds the cleanup DELETE, so a notification id
colliding with a real offer id would have deleted a stranger's proposal.

Also in this commit, from the review:

BookVisibility::hasDesiderata() no longer lets a failed probe decide on its own.
The app runs under MYSQLI_REPORT_ERROR|MYSQLI_REPORT_STRICT, so a failing probe
throws rather than returning false — the carefully reasoned "degrade gracefully"
branch was mostly unreachable, and what actually happened was an uncaught
exception out of a visibility helper, which is a 500 on every page that lists
books. Both shapes are caught now. The answer on failure is no longer a guess
either: once any probe in the worker has seen the column, a later transient
failure keeps the filter on instead of silently widening the predicate to 1=1.
Only when the column was never observed does it fall back to the old behaviour,
which is still right there — emitting a predicate on a column that may genuinely
not exist would take the catalogue down on every installation without the plugin.

The admin page's proposal query is checked before fetch_all(). The dashboard may
fall back to an empty list because the panel is decorative; the admin page may
not, because an empty backlog there reads as "nothing to judge" when the truth
is that the query failed.

The README described two things that stopped being true: that wanted books are
excluded from public search (they are deliberately findable by name, and only
excluded from browsing, feeds, the sitemap and the interop protocols), and that
uninstalling preserves the metadata (onUninstall clears the flag on every row,
soft-deleted ones included).

A club book that later became a wanted title kept showing its title to club
members. ExtensionsRepo already had catalogueOnly() and applied it correctly in
two of its three libri joins; the third was missed for a structural reason worth
naming, because it will happen again otherwise: BUDDY_SELECT was a class
constant, and a constant cannot call a method. The one query that could not use
the safety helper is exactly the one that did not. It is a method now, and the
predicate sits in the JOIN rather than the WHERE so the pairing stays resolvable
and accept/decline/done do not start 404-ing when a book goes away.

GET /api/autori had no auth middleware while its bulk-delete and bulk-export
siblings in the same block chain AdminAuthMiddleware, and it returns biografia,
sito_web and the life dates. The comment in AutoriApiController already said the
fix was to gate the route rather than filter the query; now the route is gated
and the comment no longer describes a hole.

The mobile quick-search renderer did not read item.wanted, so on a phone there
was no sign that a result is a book the library is looking for. It uses the same
PHP-injected label constant as the desktop branch.

book_form.php casts the book id before dispatching book.form.before_copies. The
handler takes ?int under strict_types, so a numeric-string id would raise a
TypeError that HookManager swallows — and a swallowed TypeError there means the
desiderata checkbox silently does not render at all.

ci-check-locales.py only recognised comments at the start of a physical line, so
a trailing // __('example') or the inner lines of a /* */ block would make CI
demand a translation key for a literal that is only an illustration. It tracks
block state and same-line comment markers now. The gate still has to bite, so
both directions were checked: a genuinely missing key is still reported, and a
commented-out example no longer is.

In the receipt picker, sync() left a stale "the selected record is an open
request" warning on screen when the operator went back to the empty option —
every path through it now leaves the status matching the selection.

Eleven of the twenty planned tests, the ones that do not need a browser:
publisher search and covers, the direct receipt's transactional and refusal
guarantees, patrons kept off the new admin surfaces, the per-recipient-locale
notifications, the plugin lifecycle and its per-locale CMS texts, and — for the
first time in this codebase — reCAPTCHA.

Each one was proven to bite before being accepted. The mutations were applied to
a scratch copy of the tree, never the working tree: removing the '1=1' allow-list
from discoverable() fails five checks in the hook suite, dropping the expected
action and the score threshold fails six in the reCAPTCHA suite, turning the
missing-token rejection into a real fail-open fails sixteen, removing the
transaction from receiveDirect() fails on the flag still being set, deleting the
open-proposals refusal fails five, and rendering every operator email in the
installation locale instead of the recipient's fails on the English operator
reading an English subject. A test nobody has watched fail is a test nobody has
checked.

Three things the plan's test list assumed and the code did not support.

The "core hooks are inert without a handler" test could not be written with
Hooks::init(new HookManager($db)): loadHooks() reads plugin_hooks, and this
installation has the plugin's twelve rows, so the test would have been exercising
the plugin while believing it was exercising core. It runs against a genuinely
empty registry, with a fresh manager per hostile handler because addHook()
appends and the accepted handler would otherwise stay in the chain.

The dashboard surface turns out to be gated twice — the core hook gate and the
plugin view's own role check — and neither alone is load-bearing. Removing the
core gate alone left the test green. Worth knowing before anyone simplifies one
away on the assumption that the test covers it.

"Exactly two captured sends" is not assertable against a live installation,
which already has two active operators. The suite asserts per seeded address
instead: one message each to the it_IT and the en_US admin, none to the
suspended one. That is installation-independent and strictly stronger.

Also here: desiderata.integration.php now sweeps by prefix as well as by
recorded id, and removes the admin_notifications rows its own offers produce.
Both gaps were real. A run in which the code accepts something the suite
expected it to refuse writes proposals nobody tracked, and an id-only cleanup
left them sitting in the operator's real backlog; and since the bell was wired,
every offer in the suite left a notification behind that nothing removed — 27
had accumulated. The LIKE patterns escape the prefix, because it contains an
underscore and an unescaped one makes DWTEST_abc also match DWTESTXabc in a
statement that deletes rows.

"«%s» è entrato in catalogo con una copia fisica" was translated with
"beholdningen", which means the holdings — the physical stock. The Italian says
the book entered the catalogue, and in this domain those are different things:
the catalogue is what the library describes, the holdings are what it physically
owns. The whole feature turns on that distinction, since a wanted book is exactly
a catalogue record with no holdings. "kataloget" is what the sentence means.

… the failure

Two review findings, both real.

The locale gate scanned every file for __() but only understood comments inside
<?php … ?>, so a // __('example') in a <script> block was collected as a real
key and CI would demand a translation for it.

The obvious fix — only scan PHP ranges — would have been a regression, and the
number says how big: window.__ is defined in 20 view files, and there are 405
genuine __() calls outside every PHP region in app/. Restricting the scan would
have stopped demanding all 405 keys, silently, which is the failure mode where a
German reader gets Italian forever and nothing says so. A false positive is
noisy; a false negative is invisible. So the scanner still looks everywhere and
now understands JavaScript comments too — but only inside a <script> body that
is not itself PHP, because // is ordinary text in HTML and treating it as a
comment there would be the same permissive mistake one layer out.

The boundaries are the whole job. JS strings are bounded at the line end, since
an unescaped newline means it was never a string and a stray apostrophe must not
swallow the rest of the file. Regex literals are lexed, and the regex-vs-division
guess leans deliberately toward regex: reading a regex as division is the
dangerous half — /[//]/ would look like a line comment — while reading a division
as a regex only skips a span and can never invent one. And a <?php inside a JS
comment still runs, so the comment span ends there and lexing resumes: the mirror
of the existing rule that ?> closes a PHP line comment. That is not hypothetical;
one settings view has five live __() calls inside HTML comments.

Proven both ways on a 12-case probe: a missing key is still reported on the PHP
side and on the JS side, a __() after a // inside a JS string is still reported,
and exactly the two commented-out cases stop being reported. On the real tree the
two versions collect the same 6983 literals — nothing lost, nothing gained.

Second finding: the extended suite's finally ran nine unguarded deletes under
MYSQLI_REPORT_STRICT. The review said a cleanup failure would replace the primary
error; in this file's shape it is worse. The catch stores the failure instead of
rethrowing, so no exception is pending at finally time and the cleanup one
escapes as an uncaught fatal — the FAIL line and the pass/fail summary never
print at all, and the message that explained the run is simply gone. Every
statement now runs in its own guard, failures are reported before the primary
result rather than instead of it, and a cleanup failure alone still exits
non-zero. Fault-injected: the other eight deletes still ran, the failure was
named, exit 1, and the primary ALL 87 PASS was still on stdout.

…uld not say why

Two CI failures on the previous commit, and they are different kinds of problem.

The reCAPTCHA unit test asserted that the capturing mailer had intercepted the
operator notifications. That is a claim about the environment, not the code: the
notification path checks Mailer::isSmtpReachable() and skips the email step
entirely when there is no mail transport, which is correct and is the normal
state of a CI runner. Locally the mail driver is present, the path runs, and the
check passed — so the test was describing this machine and failing in CI for
doing its job. What it actually needs to assert is that no real mail leaves a
test run, and that claim holds in both places; it now asserts the right half of
it depending on whether mail can be sent at all, and says so when it skips.

The second is not diagnosed, and is instrumented rather than guessed at. The
"thank you" banner assertion in desiderata.spec.js failed once in the
deep-regression shard, at position 115 of 452, and passed on neither retry.
It passes locally in isolation and in sequence with the extended spec.

What the evidence rules out: it is not the success-flag change from 0525bc1,
because the twin assertion at the end of the same file checks the same banner
after submitting from /desiderata instead of the homepage and passed in the same
CI run — if the mechanism were broken both would fail. It is not the locale,
because the buttons above it are matched by their Italian names and those
assertions passed. It is not the rate limiter, which is bypassed by an env flag
set both by the local vhost and by full-test.spec.js into CI's .env. It is not a
double render: the homepage carries one section and one form.

So rather than change code on a hunch, the assertion now attaches what the page
actually contained when it failed — the URL reached, every role=status text,
every .alert with its class, and whether the form was there at all. The next
failure will explain itself instead of needing this to be guessed again.

…the CI exemptions to the step

Unticking Desiderata on the book form used to write is_desiderata = 0 in the
metadata save and create the copies afterwards, in the post-save hook. A failure
in between left the book neither a request nor a holding: no flag, no copies, and
the operator reading "Libro aggiornato con successo!". The flag now falls inside
the transaction that creates the copies, so a failure leaves the book exactly
what it was, and the error reaches the operator instead of a success message.

That ordering also makes the lock honest: is_desiderata = 1 can now be part of
the SELECT ... FOR UPDATE predicate, the same idempotency key the direct-receipt
button already used. It could not be before, because the flag had been cleared
before the lock was taken.

The open-proposals refusal lived in the direct-receipt path only, so the same
book could be received through the book form while a donor proposal was still
pending. It is one helper now, called from both.

CI exemptions: the adhoc-packages ignores were pinned by line number in a config
file, deliberately, so that a moved step would resurface the finding rather than
be masked file-wide. The intent was right and the mechanism was not. The pins
drifted three times in one day — every time anything above them changed — each
costing a red Security check and a manual re-pin, and never once catching a real
finding. They are inline ignore comments on the steps now, which is exactly as
narrow and cannot drift. Verified by pushing the steps down five lines and
re-running: still clean, where a line pin would have gone red.

Note for anyone reaching for the same trick: the comment only works in YAML
context, on the step's name line. Inside a run block it is shell text and the
linter never sees it. The rationale moved next to the steps, where whoever edits
them will read it, and the config file is gone.

Also here: a CI step running the Book Club lending suite with
REQUIRE_DESIDERATA_TESTS=1 after the desiderata schema exists, so its
cross-plugin cases fail loudly instead of skipping; twenty release regression
cases for proposal/receipt concurrency and for member lending of wanted books;
the reCAPTCHA suite creating its own temporary operator rather than depending on
whoever happens to exist in an installation; and a changelog entry.

…-club 1.4.5

The changelog section is named now rather than at tag time, because
create-release.sh refuses to run without an exact "## [X.Y.Z]" heading and
version.json holding the same string — an Unreleased heading would have had to be
renamed under time pressure, and anything left in it would have been dropped from
the release notes, since release.yml extracts only the section matching the tag.
0.7.84 is the newest migration and every bundled requires_app is at or below
0.7.86, so both version-ordering guards still hold.

Desiderata is registered by the installer, next to emeroteca and for the same
reason: autoRegisterBundledPlugins() would only reach it on the first admin page
load, so a freshly installed library finished the wizard without it in the
completion summary and without it in the plugins list until somebody happened to
reload. It is registered INACTIVE. That was already the outcome — its manifest
carries metadata.optional, and the auto-registration reads that — but the moment
it happens is now deterministic instead of depending on a page visit.

Book-club goes to 1.4.5. Seven of its source files changed earlier on this branch
to stop publishing the title of a book the library only wants, and a manifest
that stays put makes those edits invisible to autoRegisterBundledPlugins(): it
syncs metadata only when the disk version is newer than the recorded one, so an
installation already running 1.4.4 would keep reporting 1.4.4 forever.

All of it proven against an isolated database rather than the development one,
which holds demo data the owner is walking: the real Installer and the real
PluginManager, twelve checks. A clean install registers desiderata, leaves it
off, and gives it no hooks — with open-library asserted active in the same run,
so the probe is shown to distinguish on from off rather than reporting "off" for
everything. An installation rewound to 1.4.4 moves to 1.4.5 on the next sync, and
a second sync at the same version changes nothing.

Note on the suite that checks this: plugin-integrity.spec.js skips its whole set
unless E2E_INSTALL_ROOT is exported, and the local runner does not export it. Six
tests reporting "skipped" is not six tests passing. Run with it set, they pass.

…s own plugin

A review of the whole feature branch turned up seven defects, five of them in
code the desiderata flag reaches rather than in the plugin itself. The two that
would have shipped as regressions:

A reading club lost any book the library flagged as wanted. The filter was
written as a condition on the join over `libri`, on the theory that a predicate
placed there "only empties book_title". It cannot: on a left join it empties the
entire book row, and the guard beside it — written to hide a soft-deleted book —
read that as a missing record and dropped the entry, so clubBook() returned null
and its state changes, reading schedule, polls, meetings, surveys, discussions,
buddy readings and quotes all answered 404. On the inner-join siblings the entry
simply vanished from the list. I removed the filter rather than relocating it:
/desiderata is registered with no auth middleware and publishes the whole wish
list to anonymous visitors by design, so a club naming a book its members chose
to read discloses nothing the feature does not publish itself.

The donation form's return address was an open redirect. The allow-list rejected
a leading // or /\ but judged the raw bytes, while a browser deletes tab, LF and
CR from a URL wherever they occur before parsing it — so "/<tab>\evil.example"
passed a check looking for "/\" and was then read as another host. Any control
character now refuses the value.

Also fixed: a search hit on a wanted title was counted by the result grid and
denied by every facet beside it, so clicking a filter made it disappear; adding
a favourite whose book had since been flagged destroyed the hidden entry instead
(the mobile endpoint stays as it is — it is an explicit remove, not a toggle);
a direct receipt would add a second copy to a book that already had some; the
homepage save claimed nothing had been saved when the core sections had; and the
per-book integrity sweep called bind_param() on an unchecked prepare().

The book form's save dialog now says that clearing the checkbox creates real
inventory copies. It learns this through a new extension point rather than by
being taught what a desiderata is: a plugin that injects a field can contribute
a line to the confirmation.

Three new suites, each one watched to fail against the unfixed code first:
the return-address allow-list (32 checks), a club book surviving the flag
(8, seeding its own club and rolling the whole thing back), and the search
facets counting what the results show (5). Desiderata coverage goes from 335
to 380 PHP checks. Book Club 1.4.5 -> 1.4.6, Desiderata 1.1.0 -> 1.1.1.

One reported defect did not survive checking: the claim that a stale
error_message suppresses a later save confirmation has no reachable path —
every branch that sets it redirects to a page that renders the layout.

…of my own database

"Code Quality" has been red on this branch for six commits on this one check,
and the reason is not the code it guards. It loaded the hook registry from the
installation's `plugin_hooks` table, so the dashboard panel appeared only where
the plugin happened to be switched on. On my machine it is, and the check passed;
on a clean CI schema the plugin is registered INACTIVE — it is optional, and
being off after installation is the behaviour the rest of this suite exists to
prove — so no hook rows exist and the render was empty.

The handler is now registered by the test itself, on a manager told not to
consult the database, which is what the check was always meant to be about: the
plugin's own dashboard handler and the operator gate inside it.

Verified in both directions rather than by watching it go green: with the plugin
deactivated and its twelve hook rows deleted — the CI condition, reproduced
locally — all 117 checks pass; and renaming the panel's id still fails the check,
so it has not been quietly defanged.

This is the third time on this branch that a check turned out to be asserting
something about the developer's machine rather than about the code: the reCAPTCHA
mailer check and the ConfigStore precondition were the other two.

A harvester is owed a deletion for a record it was actually given, and for
nothing else. The de-listing arms derived their tombstones from is_desiderata
alone, but that flag is reached two ways — a catalogued book WITHDRAWN, and a
book BORN as a request — and it keeps no memory of which, because the copies
that would have told them apart are deleted outright. So OAI-PMH and
ResourceSync announced removals for wishes nobody ever received, and handed
anonymous harvesters the ids and timestamps of the library's wish list.

There is now a write-once libri.catalogued_at, stamped the first time a row is
written with is_desiderata = 0 and never cleared, and the de-listing arms want
both halves. I did not follow the brief exactly: it proposed keying the stamp on
"ever had copies", but the ACTIVE arm filters on is_desiderata alone, so a
record with no copies is harvested just the same and that condition would have
stopped a genuinely withdrawn copy-less record from ever tombstoning. "Was ever
is_desiderata = 0" is what the active arm actually means.

Nor does it ship as a core migration. is_desiderata is not in schema.sql — it
belongs to the plugin and is built by its ensureSchema() — so catalogued_at
belongs there too, and the plugin version bump is what carries it to existing
installations. Rows already flagged as wanted cannot be judged retroactively and
stay NULL: the wish list loses de-listings it might have deserved, which is the
harmless half of the trade, while guessing the other way would keep announcing
deletions for records no harvester ever got. Fixed in all three places rather
than the one the finding named: GetRecord and ResourceSync carry the same arm,
and leaving two of three is how a half-done rename behaves.

Also: SÌ in a CSV's desiderata column is recognised — the parser lower-cased
byte by byte, which folds only the unaccented half of the alphabet, so the
accented affirmative worked in lower case and silently imported as an owned
holding in upper case. A donor whose book stops being wanted mid-form can now do
what the error message offers them: book_id is dropped on that one path, so the
title unlocks server-side instead of depending on a JavaScript button, and
everything already typed survives. And the plugin's three public paths are
defined once instead of being retyped in seven places across five files.

The browser fixture now WRITES the cover it needs instead of borrowing whichever
image the machine happened to have in public/uploads/copertine. That is the
fourth time on this branch a check turned out to be asserting something about
the developer's machine: it passed here, where demo covers are lying around, and
failed on a clean runner as eight "suspicious skips" and a missing-fixture error
that said nothing about the code.

Desiderata coverage goes from 380 to 445 PHP checks across eleven suites. Every
new check was watched to fail against the unfixed code first — including the
upgrade gate, which was run with the version bump reverted to confirm it catches
a schema change that would never reach an existing installation.

…d upgrades

…k the reCAPTCHA secret

desiderata-visibility and desiderata-extended rebuilt a minimal libri in the shared sandbox by dropping a fixed list of tables. When a sibling had loaded the full schema, the leftover foreign keys (copie_ibfk_1, fk_plugin_data_plugin, fk_bcbooks_libro) refused the drop or the recreate, so the outcome depended on which suite ran last. Both now empty the sandbox with foreign key checks off before building what they need. The full desiderata set passes in normal, reverse and random order.

desiderata-recaptcha restored the contacts settings only in its finally block, which does not run on a fatal error or exit(), and the test secret was written about thirty lines before that block was armed. An interrupted run left a non-empty recaptcha_secret_key behind, which the plugin treats as reCAPTCHA configured: every submission from the real donation form was answered 422 until someone noticed. The restore is now also registered as a shutdown fallback right after the snapshot, stood down once the normal cleanup has run.

Wishlist: the scoped DELETE now refuses only a live book that is currently a library request. A favourite pointing at a soft-deleted book is removable again (200 favorite:false instead of a permanent 404), and the comment names the mobile twin by its real method, ActionsController::removeWishlist().

BookVisibility: hasCataloguedAt() logs a failed probe the way hasDesiderata() does, so a probe failure that silently turns every OAI-PMH and ResourceSync de-listing off leaves a trace. Both core probes escape the LIKE underscore, matching the plugin's spelling.

Desiderata plugin: thankYouUrl() strips a fragment from the return path before choosing the query separator, so '/libro/42#recensioni' no longer buries the thank-you marker inside the fragment where the server never sees it. catalogueSearch() guards a failed prepare() and answers an empty list instead of a TypeError 500.

Book detail: a wanted title's hero badge and status dot use the neutral grey the catalogue grid already uses for the same state, through dedicated modifiers; the red stays reserved for books that are genuinely unavailable.

Also: book-club's changelog gains the missing 1.4.6 entry (the 1.4.5 behaviour it describes was reverted), a redundant is_desiderata assignment and its misleading comment are removed from FrontendController, the offer-assets comment no longer misdescribes the CSRF token, and docs/PLUGIN_HOOKS.md documents the six extension points this branch added, including the '1=1'-only allow-list on book.visibility.discoverable.

Findings: F004 F006 F009 F012 F013 F015 F016 F017 F018 F019 F020 (review rev_20260918T095032Z585542, fix run at threshold 40, all verified by an independent post-fix review).

AuthMiddleware compared the role stored in the session at login and never read the database. On the 33 routes it guards, a demoted, suspended or deleted account kept its old access for as long as its session lived (CWE-613). That includes the nine admin-only routes that use it with ['admin'] (the maintenance actions and increase-copies), and the two routes that admit every role and branch on the role inline: borrower PII on /admin/books/{id} and the activity feed on the dashboard.

SessionRoleRevalidator is now the single place that re-reads the account: one query and one cache per request, and the fresh role and state written back into the session so inline role checks further down the request read current values. The connection bootstrap moved there from AdminAuthMiddleware. AdminAuthMiddleware, AuthMiddleware and SessionRoleRefreshMiddleware all go through it, so they cannot disagree about what "still valid" means.

AuthMiddleware now requires stato = 'attivo', as the login form and the remember-me cookie already do. It ends the session of a suspended, expired or deleted account, and fails closed when the database cannot answer; a failed read leaves the session untouched.

tests/session-role-freshness.unit.php covers the behaviour against real accounts, and parses every route in web.php to fail when a handler reads the session role without a middleware that refreshes it. With the previous AuthMiddleware nine of its checks fail. docs/utenti.md explains when a role or state change takes effect and how a new route must be protected.

…umenting hooks

Desiderata plugin: deleting a proposal now goes through the same error contract as the other actions and reports a proposal that no longer exists instead of claiming success (F010). Inside the status transaction every prepare() is guarded and every handle closed before reuse, so a failure raises the RuntimeException the catch expects rather than a TypeError (F011). validateOffer() names the field that failed and its limit instead of one combined message per group (F023). The standalone /desiderata page no longer links the no-JS visitor back to itself (F021). A pre-selected, read-only title now looks locked: the plugin's inline stylesheet was overriding the .form-input[readonly] rule by print order (F022).

BookVisibility: a PHP-FPM worker whose very first desiderata probe failed answered "column absent" and published the wish list as holdings for that call. The fact that the column exists is now shared across workers through QueryCache, which is safe because the plugin never drops the column (F008).

LibriController::update() keyed its success message on any error flash already in the session, so a stale one swallowed "Libro aggiornato con successo!". It now compares against the value captured before the update, like CmsController::updateHome() (F007). scripts/ci-check-locales.py implements PHP double-quoted escapes, so "\$5" is compared as "$5" (F001). The book-club Repo docblock orphaned by the reverted desiderata filtering now documents bookSelect(), which its sibling repositories already point to (F014).

Found while documenting the hooks from their call sites: deleting a shelf or a bookcase announced success, and fired shelf.deleted, even when the DELETE matched no row. scripts/generate-sitemap.php never booted the plugin system, so a sitemap regenerated from cron or the command line silently lost every plugin page; locally that was 20 URLs instead of 562. The api-book-scraper wrapper raised "Undefined global variable $db" on every plugin load.

The extra-features E2E test for the author archive picked an author whose only book is a library request, which the public archive correctly hides. It now picks an author with a catalogued book, probing the column first so the test cannot turn into a skip on installations without the plugin.

…ences

docs/PLUGIN_HOOKS.md now describes every hook invoked from app/ and cron/: assets.footer, author.form.fields, book.admin.external_links, genre.merging, maintenance.after_run, mobile_api.dispatch_push, publisher.deleting, publisher.merging, search.external_suggestions, shelf.can_delete, shelf.deleted and sitemap.entries were missing. Each entry is taken from its call site: action or filter, arguments, what the caller does with the return value, and the constraints a handler must respect, such as merge hooks firing inside an open transaction or two cron-side call sites that only reach handlers registered in plugin_hooks.

Fifty-three file:line references were checked against the code. Nineteen pointed at the wrong line, several hooks fire from more than one place and now list each site, and the scrape.* hooks were attributed to ScrapeController although the scraping plugins emit them. The closing note now states exactly which hooks are listed and which are plugin-only.

CmsController: when only a plugin handler reports an error, the core home sections are already written. The error branch now invalidates the home cache in that case too, so visitors no longer keep the previous version until expiry.

DataIntegrity: the desiderata sweeps (bulk recalculation and per-book) clear the request flag and make a book public. Neither recorded anything in the book's history. Each fulfilled request now gets one book.updated event with source 'repair' and the system operator, written in the same transaction. The activity feed labels the two new fields.

ResourceSync and OAI-PMH: a soft-deleted request that never reached the catalogue was announced to harvesters as a deletion. That was a false sync event, and it published the request's id and timestamps. ResourceSync's soft-delete branches now require `NOT (delisted AND NOT everCatalogued)`. OAI-PMH applies the same guard when it reads oai_deleted_records, since its trigger records every book. This also covers tombstones already recorded. The literal suggestion, appending everCatalogued, would have removed every soft-delete tombstone on installations without the plugin and on unstamped ordinary holdings. tests/desiderata-soft-delete-tombstones.unit.php drives the real query methods with the trigger installed and covers both of those cases.

Translations: the uncheck-to-fulfil hints kept the Italian "Desiderata" in English and Danish, and also in German and French. They now use each language's checkbox label. The English first-contact message asks for a final confirmation instead of "one more send".

Tests: desiderata-oai-tombstones, desiderata-search-facets and desiderata-bookclub-resolvable ran ensureSchema() (DDL plus a backfill that no rollback undoes) against the installation's own database. They now run only on the disposable sandbox. desiderata-first-contact exited inside its catch, which skipped the finally cleanup; the failure is now reported after cleanup. desiderata.integration asserts that the automatic fulfilment is recorded once in the book's history.

…e notification errors

Activity feed: the search box was restored from a snapshot taken when a request LEFT. When the type filter was changed and typing started while that request was in flight, the snapshot had been taken with focus still on the select, so the swap replaced the box and discarded the keystrokes. The box is now read when the response lands; if the results answer an older query than the one on screen, the matching one is fetched. The debounced search resolves its form when it fires instead of holding a copy the previous swap may have detached. Boolean fields such as is_desiderata render as Sì/No.

Notifications: navigating away while the unread-count or list request was in flight logged "Failed to fetch" as an error on every quick page change. A request cancelled by leaving the page is no longer reported. Genuine failures still are.

The activity-feed E2E waited for text that was already in the unfiltered feed, so the search raced the swap. It now waits for the swap to complete. Before this it failed intermittently: one run in three on the previous code.

# Conflicts:
#	CHANGELOG.md
#	docs/PLUGIN_HOOKS.md
#	locale/da_DK.json
#	locale/de_DE.json
#	locale/en_US.json
#	locale/fr_FR.json
#	locale/it_IT.json

The dashboard read the pending proposals and, on a failed query,
substituted an empty array. An empty list is a fact the operator acts
on — nothing to decide today — so a failure that says it hides the
panel while the page looks healthy.

Under this project's mysqli error mode a failing query throws and the
branch is unreachable; it exists for the window where BackupManager
turns reporting off, and it now reaches the same catch as every other
failure, which logs and renders no panel.